MacFormat 1994 November

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1994 November / macformat-018.iso / Comms Spectacular / Terminal 2.2 / Documentation / Terminal.doc < prev next >

Wrap

Text File | 1992-01-17 | 58.3 KB | 1,475 lines | [TEXT/PEDT]

=========================================================================== "Terminal" A Serial Communication Program For The Macintosh =========================================================================== Version 2.0 (20-Nov-1990) ___________________________________________________________________________ INTRODUCTION "Terminal" is a serial communication program for the Macintosh computer. Features are: * Fast display. No characters are lost for up to 4800 Baud on a Mac Plus, or up to 9600 Baud on a Mac IIcx in 1-bit color mode, with text capture to disk enabled. (For most commercial programs this only holds for short term until the serial input buffer is full.) * Capture buffer, so that the last 32768 (default, can be configured, upper limit is 32768 lines) characters are always available in the scrolling terminal window. The buffer can be saved as TEXT file to disk or appended to an existing file. Very fast scrolling to move around in the buffer. * Text capture to disk, so that everything received or transmitted is saved automatically to a TEXT file on disk. Can also be appended to an existing file. * Send TEXT files from disk, from up to 10 different macro buffers or from the clipboard. Wait for prompt string before sending line, delay after each line, delay after each character. * XON/XOFF, CTS, DTR and CTS/DTR handshake. Hardware handshake is useful for high speed modems or terminal node controllers. * Binary file transfer using X-Modem protocol (checksum, CRC or 1K options), Y-Modem (i.e. XModem batch), Z-Modem or CompuServe QuickB protocol (up- and download). Automatic recognition of MacBinary (I and II) file format. * Built-in C interpreter with a rich set of intrinsic functions to execute scripts from TEXT files. Scripts can be as simple as modem setup, dial or auto-logon, but can also be used to program a complete BBS. * Very compact program. Only about 90K on disk and can run in a 160K partition under MultiFinder. * Complete non-modal user driven program (even during file transfers). Runs in the background under MultiFinder (even if "Set Aside" under MultiFinder). Several copies of the program may be run at the same time, under MultiFinder, each one on a different serial port. * Recognizes and uses all serial devices that are correctly registered with the Communications Toolbox. * The program is free. * Source code is free (can be compiled with THINK C 4.02 or MPW 3.2 C). ___________________________________________________________________________ CONFIGURATION "Terminal" was developed (in THINK C 4.02 and MPW 3.2) and tested on a Macintosh Plus and on a Macintosh IIcx with System 6.05 under MultiFinder 6.1b9 (The MultiFinder with the "Set Aside" option). The program is MultiFinder aware and can work in the background even if "Set Aside". HFS (hierarchical file system) and 128K ROMs (or newer) are required, so "Terminal" will not run on "old" Macs and needs at least a Mac Plus. "Terminal" was tested and runs fine with System 7.0b1 (October release). I made no special attempts to stay compatible with old system versions, nor was the program tested on old system versions. But I made every effort to follow Apple's rules in order to stay compatible with future systems and hardware. (The only exception is the script function getdcd() where I had to read the status register of the SCC directly.) "Terminal" will recognize all serial devices that are correctly registered with the Communications Toolbox, but otherwise does not use or require the Communications Toolbox. ___________________________________________________________________________ FILES AND FOLDERS * "Terminal" the application, can be anywhere on your disk. * "Terminal Folder" is a folder that should be created in the same folder as the "Terminal" application. All scripts (a script is a TEXT file with a suffix of ".s") in this folder will be included in the "Scripts" menu for easy execution. If this folder does not exist, all scripts in the same folder as the "Terminal" application will be included in the "Scripts" menu. This script folder, or the application folder if the script folder does not exist, is also used as the default folder for loading macro files by the script language (function "macrol"). If there is a file named "Macros.m" in this folder it will be loaded as the macro set at startup. * "Terminal Settings" is created by "Terminal" in the "Terminal Folder", or in the application folder if "Terminal Folder" does not exist, to store the options selected. If this file is not found when "Terminal" starts up, default options will be used. In this file are also stored the current positions of the terminal and the progress window, so that they will be positioned again at the same location when the application is restarted. (The settings file is not stored in the System folder so that multiple copies of "Terminal" can run on the same machine, under MultiFinder, each one on a different port.) * The "Terminal options" menu can be used to select a start-up script, that will be automatically executed when the application is started. This script can be anywhere on the disk. By default there is no start-up script. A script can force "Terminal" to quit when the script has finished. Using this feature and a startup script you can use Terminal to make file transfers from inside HyperCard stacks (you can even make HyperCard modify the startup script before running Terminal), or from other programmable applications that support launching other applications. * Scripts can be started from the Finder by double-clicking (opening) if their creator was changed from the creator of the TEXT editor that created them to Terminal's creator. See the "Kiss script file" command in the "File" menu description. * For use with Y-Modem batch, Z-Modem and CompuServe QuickB file transfers a folder must exist on the disk where all downloads and uploads using these protocols will look for and store files. This folder can be selected by using the "File transfer options" menu option. The default folder is the same as the folder containing the "Terminal" application. This folder is also the default folder used by script file commands. Note: If you had a previous version of "Terminal" on your disk please rebuild the Desktop file (hold down the option and the command key when booting) so that the Finder recognizes the new icons and file types. ___________________________________________________________________________ THE TERMINAL WINDOW There is a fixed size window with 24 lines and 81 columns (default values, can be configured). The window can be moved anywhere on the screen. A vertical scroll bar allows fast moving around in the last 32768 (default value, can be configured) characters received. If a new character is received the text automatically scrolls to the end. Everything received is displayed in the terminal window, even if the window is not the frontmost or if the application was switched out under MultiFinder. Note: "Terminal" tries to scroll the window as fast as possible. If the window is partially covered by other windows, the scrolling slows down some what. If during scrolling you move windows around, the terminal window might not update correctly. In this case simply click inside the terminal window to force "Terminal" to redraw the whole window. The name of the window will be "Terminal" if no script is executing, otherwise the window name will be the same as the name of the script file. To cancel a running script select it again under the corresponding menu item. If the terminal window is frontmost everything typed on the keyboard is transmitted. If the local-echo option is selected it is also echoed to the window. To send control characters the "Option" key (in this case all characters that are only available by using the "Option" key are no longer available) or the "Command" key (in this case the "Command" key cannot be used to select menu commands) can replace the "Control" key, if your keyboard doesn't have one. After file transfers a statistics message is displayed in the top area of the window showing how much bytes were transferred in how much time. This area is also used to display error messages. If a message is displayed a button appears to the left of it. Clicking this button will erase the message and the button. Note that such a message is not a modal dialog but will stay as long as there is no new message or until it is cleared. Meanwhile the program continues its normal operation. During file transfers a progress window (this is a non-modal window, not a modal dialog box, and can be moved around or deselected, and all menu commands are still available while this window is up) is displayed. This progress window shows the progress of the file transfer and has a "Cancel" button. By clicking in this "Cancel" button the file transfer can be aborted. The file transfer can also be canceled by selecting the corresponding menu item. If the progress window gets lost beneath other windows, use the "Edit" menu item "Show progress window". Characters received in terminal mode are filtered using the following criteria (this is what I consider basic TTY emulation): * All bytes received will get their most significant bit stripped to make 7 bit ASCII characters. * A "CR" character (carriage return, ASCII 13) will move the cursor to the first position in the next line. * A "Backspace" character will erase the last character received and move the cursor one position to the left, but will never move to the previous line. The code to be recognized as "Backspace" can be chosen (see "Options menu"). If TEXT file capture is on, all characters are saved as received in the file including the "Backspace" characters. * A "TAB" character (ASCII 9) will be accepted (and saved if TEXT file capture is on) but displayed as a space character. * Five consecutive "CAN" (control-X, ASCII 24) are recognized as a signal to abort text file sends, X/Y-Modem or ZModem file transfers. * A "BEL" (control-G, ASCII 7) is recognized and if this feature is enabled via the "Other options..." menu item, the Macintosh will beep. The "BEL" character is not saved to the terminal buffer or capture file. * All other control characters are ignored and only characters with ASCII codes higher then 32 and lower than 126 are accepted (printable characters). * If lines longer than 81 (depends on the configured window width) characters are received a "CR" will be inserted automatically after every 81 characters, and this "CR" will also be saved to disk if TEXT capture is on. ___________________________________________________________________________ THE "FILE" MENU SAVE CAPTURE BUFFER A standard file dialog is presented (if the capture buffer is not empty) allowing to save the contents of the capture buffer to disk as a TEXT file. The TEXT file creator can be changed using the "Text capture option" item in the "OPTIONS" menu. If a modifier key (shift, command or option) is pressed while selecting the menu option the capture buffer gets appended to the end of an existing TEXT file. TEXT CAPTURE A standard file dialog is presented allowing to create the TEXT file where all further input or output will be saved. The TEXT file creator can be changed using the "Text capture option" item in the "OPTIONS" menu. The menu text will change to outlined and expanded, so that when selected again the capture file will be closed. The file is also automatically closed when quitting the program. If a modifier key (shift, command or option) is pressed while selecting the menu option the capture buffer gets appended to the end of an existing TEXT file. TEXT SEND A standard file dialog is presented to select a TEXT file. The file contents is sent using the options that can be selected in the "TEXT file transfer options..." item of the "Options" menu. The menu text will change to outlined and expanded, so that when selected again the transmission will be canceled. If five control-X characters are received the transmission is also canceled. FILE RECEIVE If X/Y-Modem is enabled and if Y-Modem batch is active, or if Z-Modem is enabled, the file transfer starts immediately. During such a session more than one file my be received. All files received are stored in the folder selected by the "Binary File Transfer Options" dialog. If MacBinary file format is enabled, the file name used will be the name from the MacBinary header if this name does not yet exist, otherwise the name from the Y-Modem header (block 0) or the Z-Modem file information block will be used, and if a file with this name exists it is deleted first. If MacBinary is disabled the file name from the Y-Modem header (block 0), or the Z-Modem file information block, is used, and if a file with this name exists it is deleted first. Note: Z-Modem creates a temporary file while receiving. This file is not deleted when the Z-Modem transfer is aborted. Instead when the Z-Modem receive is resumed later on, it will continue were it stopped before. This partial Z-Modem file has a special file type and a distinct icon. Only when the receive is complete, will the file type changed to what it should be. If X/Y-Modem without the batch option (i.e. X-Modem) is chosen a standard file dialog is presented to create a file to be used for binary file receive using X-Modem protocol. The X-Modem protocol file receive session is started. If MacBinary file format is enabled, the file name used will be the name from the MacBinary header if this name does not yet exist, otherwise the first chosen name will be used. Note: For CompuServe QuickB protocol file transfers there is no need for this menu option as the transfers will be initiated by the host and the host will prompt you for the file name on your computer. For ZModem receive there is an option (that can be set in the Z-Modem options dialog) to automatically start the receive, so the FILE RECEIVE menu command need not be used. FILE TRANSMIT A standard file dialog is presented to select the binary file to transmit using X/Y-Modem or Z-Modem protocol. If the MacBinary file format is enabled the file is sent in MacBinary II format. In Y-Modem batch, or Z-Modem, only one file can be send in a session. Note: For CompuServe QuickB protocol file transfers there is no need for this menu option as the transfers will be initiated by the host and the host will prompt you for the file name on your computer. MAKE MACBINARY FILE Use this utility option to create a MacBinary II file from any other file on your disk. The MacBinary file gets a special file type and a distinct icon. Normally this operation need not to be used, because the FILE TRANSMIT menu command will create the MacBinary II file on the fly while transmitting. EXTRACT FROM MACBINARY FILE Use this utility option to extract a file from a MacBinary I or MacBinary II file on your disk. This is useful if you have forgotten to enable automatic MacBinary recognition and you have already downloaded a file. KISS SCRIPT FILE Use this utility option to change the creator of TEXT files so that the "Finder" recognizes them as "Terminal" documents. In this way you can double-click the script file and it will automatically be executed by "Terminal". Only TEXT files with a file name ending in ".s" can be changed. To change back the creator of the TEXT file to the creator of the text editor application, hold down the option key while selecting the KISS SCRIPT FILE menu command. The creator of the TEXT file will be set to the TEXT file creator you have set in the OTHER OPTIONS dialog. When you now double-click the script file, the text editor will open it. QUIT To quit and return to the "Finder" use this option or click in the close box of the terminal window. ___________________________________________________________________________ THE "EDIT" MENU The first five items are there for desk accessories. Only the following is used: PASTE The text in the clipboard is sent using the options that can be selected in the "TEXT file transfer options..." item of the "Options" menu. The menu text will change to outlined and expanded, so that when selected again the transmission will be canceled. If five control-X characters are received the transmission is also canceled. CLEAR CAPTURE BUFFER This will clear the capture buffer and the terminal window. SHOW PROGRESS WINDOW This selects the progress window and brings it to the front. Useful if the progress window gets covered by other windows. DEBLOCK SEND This kills any outstanding serial write request. It might be useful if the program has received an XOFF, but never got the XON. NEGATE DTR This negates the DTR output (output handshake signal). ASSERT DTR This asserts the DTR output (output handshake signal). CHECK CTS This displays the current status of the CTS input (input handshake signal) in the status message window. ___________________________________________________________________________ THE "OPTIONS" MENU The options selected in the following dialogs are saved in a file, so that they are again available when the program is started at a later time (the file name is "Terminal Settings"). If no options file is found when the program is started, default values will be used. COMMUNICATION * Port: None, "Modem", "Printer" or any other serial port available. * Baud rate: 300 to 56700 Baud. * Data bits: 7 or 8. * Stop bits: 1 or 2. * Parity: even, odd or none. * Handshake: XON/XOFF, CTS only, DTR only, CTS and DTR. * Don't drop DTR when quitting: useful if you don't want the modem to hang-up when you quit the program. Note: During X/Y-Modem or QuickB binary file transfers the data bits are set to 8 bits. When the transfer is finished the original value is restored. Z-Modem automatically will escape all characters that use the high order bit if 7 data bits are used thus enabling binary file transfers over non-transparent links. TEXT FILE SEND * Wait for prompt before sending next line: If this option is checked the program will wait for the prompt string (this can be more than one character) before sending the next line while sending TEXT files. * Delay after each line sent: If this option is checked the program waits for the specified number of ticks (1/60 second) before sending the next line while sending TEXT files. * Delay after each character sent: If this option is checked the program waits the specified number of ticks (1/60 second) before sending the next character while sending TEXT files. Note: the TEXT file send parameters are also used when sending macros or pasting text from the clipboard. TERMINAL * Echo: local (display keyboard characters), remote (retransmit received characters). * Display and capture: if checked the capture window and buffer are active, else nothing is displayed nor captured. * AutoLF: If this option is checked a linefeed character will be send after each carriage return character. * Start-up script: Any script can be selected to be executed automatically when the "Terminal" application is started. OTHER * Text capture file creator: file creator for TEXT files used for saving the capture buffer or by the "Text file capture" option. So if you double- click on these files your favorite text editor program is automatically called. If you un-kiss (see FILE MENU) script files they will get this creator. * File type and creator for non-MacBinary files: if automatic MacBinary file format recognition is not enabled, or if the file received is not a valid MacBinary file, this type (default is 'TEXT') and creator are used for the new file. * Code for "backspace" key: ASCII code send by pressing the "Backspace" key, and also the ASCII code recognized as "Backspace" code while receiving. * Code for "`" key: ASCII code send by pressing the "`" key. This can be used to make an "ESC" key (ASCII 27) on keyboards that don't have an "ESC" key. * Control-G beeps: if checked any "BEL" (control-G, ASCII 7) character received will beep. * Control key: the keyboard modifier key to be used for sending control characters (e.g. cntl-C). On keyboards lacking a "control" key, use either the "option" key (in this case you cannot send the characters that normally are only available by using the "option" key) or the "command" key (in this case you cannot execute menu commands by key equivalent). BINARY FILE TRANSFER * MacBinary: use and recognize MacBinary file format in file transfers (Note that TEXT files are never sent as MacBinary). * CIS-B: recognize and use CompuServe QuickB protocol for file transfers. If you don't use QuickB uncheck this option. This makes things faster and eliminates any false triggering into file transfer mode on noisy lines. * X/Y-MODEM: use X-Modem or Y-Modem file transfers when using the "Receive..." or "Transmit..." commands from the FILE menu. Options can be set in the "XY-Modem Options..." dialog. * Z-MODEM: use Z-Modem file transfers when using the "Receive..." or "Transmit..." commands from the FILE menu. Options can be set in the "Z-Modem Options..." dialog. * Auto-receive: when this is checked, Z-Modem receive will start automatically as soon as a the other side has started transmitting. If you rarely make Z-Modem file transfers, don't check this. This makes things faster. The likelihood of false triggering is small, but nevertheless exists. * Path for up- and downloads: folder name used for CIS-B up- and downloads (because the host will only prompt for the file name on your computer but not the path name), for Y-Modem batch or Z-Modem file downloads (where only the file name is in the header block). XY-MODEM OPTIONS * CRC If not checked "classic" X-Modem with simple checksum and 128 Byte blocks will be used. The "1K" options are disabled. If checked CRC error checking will be used and the "1K" options are enabled. * 1K off 128 Byte blocks are used. aut 128 or 1024 Byte blocks are used automatically and where appropriate. During the initial handshaking phase the single character "C" is used. This is the "official" way of doing it. CK 1024 Byte blocks are used if during the initial handshaking phase the two character sequence "CK" is used (this is used by Red Ryder 10.3 and perhaps others). * batch off No batch protocol is used, i.e. this is X-Modem. Y "Official" Y-Modem batch protocol is used. RR A variant of the Y-Modem batch protocol is used where there is no new handshaking phase after the header block (block 0) has been sent (this is used by Red Ryder 10.3 and perhaps others). * timeout Select the value 5, 10, 15 or 20 seconds. Z-MODEM OPTIONS The first three options are used for receive and transmit. * Escape control characters: if this is checked all control characters are escaped (including all characters who have their high order bit set). This slows down Z-Modem but must be used on non-transparent links. In any case, if using 7 data bits, Z-Modem will ignore this setting and escape all control characters. * Timeout (seconds): should be set at 10 seconds. * Maximal retries: should be set at 10. The following option is only for Z-Modem receive. * Receive buffer size (bytes): can be set to 0 or a value between 128 and 32768. If set to 0 the receiver signals to the transmitter that it is able to receive and save data as fast as it is coming in. Otherwise the sender will make sure to never have more than this number of non-acknowledged bytes and waits while the receiver will save the data. The following options are only used for Z-Modem transmit. * Transmit sub-packet length (bytes): can be set to 256 for speeds up to 1200 Baud, 512 for speeds between 1200 and 2400 Baud, and to 1024 (maximum) for higher speeds as recommended in the Z-Modem specifications. The optimum value depends on the link quality. On good links, 1024 (maximum) should be used. * Window limit (bytes): can be set to a value between 0 and 32768. If set to 0 now transmit window is used. Otherwise the sender makes sure to never have more than this number of non-acknowledged bytes. * ZCRQ spacing (bytes): can be set to a value between 0 and 32768. If set to 0 the sender will not send ZCRQ frames. Otherwise it will send a ZCRQ frame after having send this number of bytes. ZCRQ frames are used to see how far the receiver has got, but will otherwise not interrupt the data stream. You should consult the Z-Modem specifications to get more details about these parameters. The default values should be fine for most cases. ___________________________________________________________________________ THE "MACROS" MENU A macro is a text string kept in memory. There are 10 macro string buffers available. There is a different menu item for each possible buffer. The menu item name is the macro name, not it's content. The only limit for the length of a macro string length is available memory. The command key equivalents are 0 to 9. When the menu item is selected, or when the corresponding command key is pressed, the macro string is send out through the serial port using the parameters that are normally used for sending text files (prompt string, line and character delays, handshake option). So macro strings behave like text files, but are kept in memory and can be send easily with single keystrokes. If you press the option or the shift key while selecting a macro, the macro string is not send out but simply displayed in the terminal window. This can be used to test macro sets. The first menu item is used to load a new macros file using a standard get file dialog. A macros file is a simple TEXT file with a ".m" suffix, that contains a complete set of macros, up to 10 different macros. This text file can be created and edited with any TEXT editor. If there exists a file named "Macros.m" in the script folder it will be used automatically when the Terminal program is started. The contents of the macros file must respect the following rules: * Macro names start with the two characters "\m" (or "\M") and continue until the end of the line. They will get truncated to 30 characters in the "Macros" menu. * All the text following a macro name becomes the macro text, including any line returns, they are translated to carriage return characters. The macro text stops one character before (the last character, usually the final line return, is not included) the beginning of a new macro name, or at the end of the file. The only limit for the length of macro text is available memory. * To include the backlash character in macro text use the two character sequence "\\". To include control characters, other than the carriage return which is the same as control-M, use the two character sequence "\x", where "x" is the control character to use. E.g. to include control-C use "\C" (or "\c"). * Macros found in the macros file will get numbered automatically starting at 0. Macro numbers not used will get disabled in the menu. See the included examples of some macro files to see how they might look like. Note: the macro files to be loaded by the script function "macrol" must be in the "Terminal folder". ___________________________________________________________________________ THE "SCRIPTS" MENU A script is a TEXT file containing a program written in "Terminal" script language, which is a subset of the C language. Scripts are interpreted by "Terminal", there is no compilation step involved. The easiest way to maintain scripts is to use a desk accessory TEXT editor. If you use a word processor, you must save the script files as pure TEXT, not in the native format of the word processor. The first item in this menu can be used to select any script file on your disk using a standard file dialog box. Only TEXT files with a suffix of ".s" are considered to be scripts. The other items depend on what "Terminal" found in it's folder when it was started. If a folder "Terminal Folder" exists in the application folder, all script files found there are included in the menu. If no such folder exists all script files found in the application folder are listed in the menu. Selecting a script in the menu will start it. The menu item name changes to outlined and expanded. To cancel a running script simply select it's menu item again. If a script is running the terminal window's name is set to the name of the executing script. Only one script at a time can be executing. Any script can be selected to execute automatically when "Terminal" is started by using the "Terminal Options" menu. You can also double-click script files from the Finder, if they have been "kissed" before (see FILE menu commands). They are automatically opened and executed by "Terminal". ___________________________________________________________________________ THE SCRIPT LANGUAGE The script language interpreted by "Terminal" is a subset of C with many specialized intrinsic (built-in) functions. Please read a C reference book to learn the C syntax, or see the enclosed script examples to get a feeling of the language. I will not write a book about programming in C here, only tell you the essentials. PROGRAM A program is recognized as a script if it is in a TEXT file, and if the file name ends in ".s". Spaces, tabs and carriage return characters are considered to be white space. No identifier and no keyword can be separated by white space. A program consists of: comments, global variable definitions and function definitions. Everything included between "/*" and "*/" is considered a comment and will not be interpreted. Comments cannot be nested. The "/*" and "*/" are not recognized as comment delimiters inside string or character constants. Global variables are those variables that are known to all functions, unless their names are reused as local variables. Global variables can be initialized using any expression that involves either constants or other globals that are already defined at that point. Function definitions can appear in any order and their must be at least one function called "main" with no parameters. It is this function that is called when the script is started. Every function is supposed to return an integer value as result. If there is no return statement in a function, 0 will be returned. Functions can be called recursively. There are many built-in functions that are already defined when the script is started. The value the "main" function returns is used as follows: 0 : Don't restore saved settings, continue application 1 : Restore saved settings, continue application 256 : Don't restore saved settings, quit application 257 : Restore saved settings, quit application Restore saved settings means that all changes the script made to settings are forgotten as soon as the script finishes. Quit application means, that as soon as the script has finished, "Terminal" quits. Usually this means returning to the Finder. But if "Terminal" was launched from HyperCard it will return to HyperCard. This is an example of a simple script that displays the message "The number is 123" in the terminal window: int Number = 123; /* This is a global variable */ main () /* Every script must have a main() function */ { /* display() is a built-in function */ display("The number is %i\r", Number); } IDENTIFIERS An identifier is a sequence of letters and digits; the first character must be a letter. The underscore "_" counts as a letter. An identifier can be of any length up to 255 characters. All characters are significant and are case sensitive. There are three types of identifiers: keywords, function names, variable names. The keywords are: "break", "char", "else", "for", "if", "int", "return", "while". CONSTANTS An integer constant is a sequence of decimal digits, or 0x followed by up to 8 hexadecimal digits. An integer value is represented internally by 4 bytes (32 bits). A minus sign before a constant is considered as an unary operator, not a part of the constant itself. A character constant is a sequence of 1 to 4 characters enclosed in single quotes. Character constants are converted to integer values, the byte values corresponding to the ASCII codes of the characters. A string constant is a sequence of characters enclosed in double quotes. String constants are automatically terminated by a NULL character. The value of a string constant is the address of the first character. Some examples of valid constants: 1234567 0xABCD1234 'a' 'TEXT' "An apple a day keeps troubles away" In character and string constants the backslash "\" is used as an escape sequence according to the following table: LF 0x0A \n TAB 0x09 \t FF 0x0C \f BELL 0x07 \a BS 0x08 \b CR 0x0D \r VT 0x0B \v NULL 0x00 \0 any 0x.. \x.. (2 hex digits) If the character following a backslash is not one of those specified the backslash is ignored. This can be used to represent the backslash itself, to put a single quote into a character constant or to put a double quote into a string constant. Some examples; "Going to the next line...\r" '\0' "This is a single backslash: \\" "\"Hello world!\"" '\'' '\x03' /* That's a control-C */ VARIABLES There are four types of variables: characters, integers, pointers and arrays. Integers represent 32 bit signed values and characters 8 bit signed values. Pointers hold the 32 bit address of integers, characters or other pointers. Arrays are more or less equivalent to pointers. The following examples show how variables are defined: char c; /* "c" is a character variable */ int n; /* "n" is an integer variable */ char *ptr; /* "ptr" is a pointer to characters */ char **hdl; /* "hdl" is a pointer to character pointers */ int *p; /* "p" is a pointer to integers */ int **q; /* "q" is a pointer to integer pointers */ char a[80]; /* "a" points to an array of 80 characters (80 bytes) */ int b[10]; /* "b" points to an array of 10 integers (40 bytes) */ char *c[5]; /* "c" points to an array of 5 character pointers (20 b) */ int *d[5]; /* "d" points to an array of 5 integer pointers (20 b) */ Variable declarations can be grouped together like this: char c, *ptr, **hdl, a[80], *c[5]; int n, *p, **q, b[10], *d[5]; Variables can be initialized using any legal expression, not only constants. Arrays can only be initialized at the global level, i.e. outside of function definitions. Initialized arrays must not include their size between the square brackets, the size is calculated based on the initializing values. char c = 'x'; int n = -123; int m = n * 10; /* "m" is set to -1230 */ char message[] = "This is a character string"; char *messages[] = /* Array of strings */ { "This is string #1", "Another string", "and so on..." }; int a[] = { 1, 2, 3, 4, 5 }; /* Array of 5 integers */ The are no logical variables. Everything that is not zero is considered to be true. EXPRESSIONS The following is a list of the supported operators that build up an expression. The list is by increasing precedence. Normally operators group left to right unless otherwise noted below. Note that the assignment is an operator, that an expression may contain several assignments, and that an assignment returns a value. Logical and numerical operators can be freely mixed, everything not zero is considered to be true. The precedence level can be changed by using parentheses. The boolean operators will return 1 as true. Assignment = (right to left) Logical or || Logical and && Equal, not equal == != Relational operators < <= > >= Add, subtract + - Multiply, divide, modulo * / % Logical not, increment, decrement, unary minus, indirection, address of ! ++ -- - * & (right to left) Function call, array element () [] The increment or decrement operators can be used before or after a variable. If the operator comes before the variable (preincrement, predecrement) the variable is incremented, or decremented, and then the variable's value is used in the expression evaluation. If the operator comes after the variable (postincrement, postdecrement) the current value of the variable is used in the expression evaluation, and then the variable is incremented, or decremented. Array subscripts start with 0. There is no runtime check of array boundaries. An array subscript can be any valid expression. Some examples: char a[80]; c = a[0]; /* The first element */ c = a[79]; /* The last element */ c = a[i = (79 - Func(x)*3)]; /* Expression as subscript */ For pointer arithmetic the following rules apply: if an integer value is added or subtracted from a pointer (a pointer is an address) then the integer value is first scaled depending on what the pointer is pointing to: 1 for characters, 4 for integers, 4 for pointers. If two pointers are subtracted the result is scaled in the same way and yields an integer value representing the number of objects separated by the two pointers. The two pointers must point to the same type of objects. A function identifier without a parameter list in an expression results in the address of the function being used. If there is a parameter list, the function is called and the integer value returned by the function is used. Functions can also be called indirectly, using any expression that yields a valid function address followed by a parameter list. Some examples: int pf; /* "int" can be used as function pointer */ int i; pf = Func; /* "pf" will contain address of function "Func" */ i = Func(); /* "i" gets function result */ i = (pf)(); /* "i" gets function result */ FUNCTIONS A function definition can only occur in the outer, global level. A function cannot be defined inside another function. All functions are supposed to return integers. A function definition consists of the function name, followed by a parameter definition list enclosed in parentheses, followed by a compound statement. The parameter definition list describes the function parameters. These parameters are considered as local variables inside the function. Example: /* The following function takes 3 parameters: a character, an integer and a character pointer. It always returns the value 123. */ Function (char c, int i, char *p) { /* ... */ return 123; } A function call consists of the function name followed by a parameter list. The parameter list is a comma separated list enclosed in parentheses of expressions. All parameters are passed by value. There is no verification if the number of parameters is correct or if the values passed to a function correspond to the types of the declared parameters. Example: i = Function ('x', 4567 + x, "Hello"); STATEMENTS A compound statement starts with an open brace "{" and terminates with a closing brace "}". There is an optional variable definition part followed by a list of statements. Variables defined inside a compound statement are local to that compound statement (block). A statement can be: compound statement expression ; if ( expression ) statement if ( expression ) statement else statement while ( expression ) statement for ( opt expr1 ; opt expr2 ; opt expr3 ) statement break ; return ; return expression ; ; The two forms of the conditional statement are: if ( expression ) statement if ( expression ) statement else statement In both cases the expression is evaluated and if it is nonzero, the first substatement is executed. In the second case the second substatement is executed if the expression is 0. The "else" ambiguity is resolved by connected an "else" with the last encountered "else"-less "if". The "while" statement has the form: while ( expression ) statement The substatement is executed repeatedly so long as the value of the expression remains nonzero. The test takes place before each execution of the statement. The "for" statement has the form: for ( opt expr1 ; opt expr2 ; opt expr3 ) statement This statement is equivalent to: expression1 ; while ( expression2 ) { statement expression3; } Thus the first expression specifies initialization for the loop, the second specifies a test, made before each iteration, such that the loop is exited when the expression becomes 0; the third expression often specifies an incrementation which is performed after each iteration. Any or all of the expressions may be dropped. A missing expression2 makes the implied "while" clause equivalent to while(1); other missing expressions are simply dropped from the expansion above. The statement break ; causes termination of the smallest enclosing "while" or "for" statement; control passes to the statement following the terminating statement. A function returns to its caller by means of the "return" statement, which has one of the forms: return ; return expression ; In the first case the returned value is undefined. In the second case the value of the expression is returned to the caller of the function. If required, the expression is converted to an integer. Flowing off the end of a function is equivalent to a return with no return value. The null statement has the form ; A null statement is useful to supply a null body to a looping statement such as "while". Note: Unlike real C, logical expressions are completely evaluated, even if their TRUEthness (different from 0) ore FALSEness (equal to 0) can be determined before the whole expression is evaluated. In real C that's called short circuit boolean evaluation. For example in the statement if (dothis() && dothat()) ; the functions dothis() and dothat() are always called in script C. In real C the function dothat() is only called if dothis() returns a non-zero result. ___________________________________________________________________________ INTRINSIC FUNCTIONS Intrinsic functions are built-in and need not to be defined in the script. They can be called by any script. All file access functions operate on the file transfer up- and download folder, which is the folder that can be set with the "Binary file transfer options..." menu item. File names can be up to 31 characters long and cannot contain the character ':'. All formatting functions ("display", "format", "type") use a template string to specify the formatting to be done on the following parameters. Format specifiers begin with the character % and include zero or more of the following conversion specification elements (optional fields are in brackets): % [option flags] [field size] conversion Some of these elements are optional, but if present, they must be specified in the order in which they are described below. Option flags (optional): - Left adjust output in field, pad on right (default is to right justify). 0 Use zero (0) rather than space for the pad character Field size specification (optional): The minimum field width, expressed as a decimal integer. The corresponding parameter will be printed in a field at least this wide. Conversion characters (required) c Parameter is a character i Parameter is an integer s Parameter is a null terminated string % Print a %, no parameter used The format specification elements must correspond to the following parameters. Some examples: char k, m[80]; int n; type("Unrecognized character %c on line %i of file %s\r", k, n, m); The following list describes all the existing intrinsic functions. They are described in the so-called prototype format, i.e. the format you would have to use to define them. E.g. xxxx (char *s, int i) means that "xxxx" is a function taking 2 arguments, the first is a pointer to a character and the second is an integer. Note that all functions return integers, but the value returned is not necessarily meaningful for very function. autolf Set the auto linefeed flag on or off autolf (int flg) flg: 0 means off, 1 means on beep Macintosh system beep beep () capture Start/stop capture to text file capture (int opt, char *name) result: Macintosh file system error, 0 if no error opt: 0 = Close capture file 1 = Capture on, new file 2 = Capture on, append to existing file name: Pointer to character string of at least 32 characters. This is the file name. catalog Return file info catalog (int i, char *name, int *type, int *dsize, int *rsize, int *cdate, int *mdate) result: Macintosh file system error, 0 if no error i: If 0, then name must be specified and information about the file with that name is returned, if it exists. If non-zero information (including file name) about the i-th file in the folder is returned. name: Pointer to character string of at least 32 characters. This is the file name (specified or returned depending on the value of i). type: Integer (4 bytes). File type. dsize: Data fork size in bytes. rsize: Resource fork size in bytes. cdate: Creation date in seconds. mdate: Modification date in seconds. date Convert seconds from Macintosh clock to date and time date (int sec, int *yr, int *mo, int *da, int *ho, int *mi, int *se, int *dw) sec: Seconds yr: Year (1904..20xx) mo: Month (1..12) da: Day (1..31) ho: Hour (0..23) mi: Minutes (0..59) se: Seconds (0..59) dw: Day of week (1..7, Sunday is 1) display Display in the terminal window display (char *templ, ...) templ: Template string ...: Variable number of arguments (maximum 9) download Download (receive) a binary file using X/Y/Z-Modem protocol download (char *name, int bin, int zmodem) result: Error code. 0 if Ok. 1 if timeout. 2 if cancel. 3 if abort (5 consecutive control-X characters received). All other values are Macintosh file system errors. name: File name for new file (not used for Y-Modem batch or Z-Modem) bin: 1 to recognize and use MacBinary format zmodem: 0 use X/Y-Modem, 1 use Z-Modem format Formatted conversion of values into a string format (char *str, char *templ, ...) str: String for result templ: Template string ...: Variable number of arguments (maximum 8) free Dispose of the memory allocated by the new() function free (char *p) p: Pointer returned by previous call to new() function getcts Get current state of CTS input line getcts () result: 0 if negated, 1 if asserted getdcd Get current state of DCD input line getdcd () result: 0 if negated, 1 if asserted lecho Set the local echo flag on or off lecho (int flg) flg: 0 means off, 1 means on macrol Load new macros file macrol (char *name) result: Error code, 0 means no error name: File name of TEXT file with macros (folder will be the same as the "Terminal folder") macrox Execute macro macrox (int i, int op, char *name) result: Error code, 0 ok, 2 cancel, 3 abort (2 consecutive control-X characters received) i: Macro number (0 to 9) op: 0 send macro text (using send TEXT file parameters), 1 display macro text, 2 return macro name name: Only used if op is 2, should point to a string where macro name will be returned (at least 30 characters long) move Move bytes from source to destination move (char *src, char *dest, int cnt) src: Source pointer dest: destination pointer cnt: number of bytes to move new Allocate memory new (int size) result: Pointer to memory, or 0 if not enough memory available size: Number of bytes to allocate nextbuff Wait for some characters nextbuff (char *buff, int count, int t) result: count characters received, 1 timeout, 2 cancel, 3 abort (5 consecutive control-X characters received) count: Number of characters to wait for buff: Character buffer to hold received characters. Must be at least count characters long t: Timeout value in ticks (1/60th of second) nextline Wait for the next line received over the serial input port nextline (char *line, int t) result: 0 line received, 1 timeout, 2 cancel, 3 abort (5 consecutive control-X characters received) line: String to hold line, this will be a '\0' terminated string without the final carriage return t: Timeout value in ticks (1/60th of second) pause Pause for specified amount of time pause (int t) result: 1 timeout, 2 cancel. t: Timeout value in ticks (1/60th of second) prompt Wait for a prompt string to come over the serial input port prompt (char *str, int t) err: 0 string received, 1 timeout, 2 cancel, 3 abort (5 consecutive control-X characters received). str: String to wait for (case sensitive) t: Timeout value in ticks (1/60th of second) protocol Set binary file transfer options protocol (bin, qb, zmodem, autorx) bin: 0 no MacBinary, 1 use MacBinary, -1 no change qb: 0 no QuickB, 1 use QuickB, -1 no change zmodem: 0 Z/Y-Modem, 1 Z-Modem, -1 no change autorx: 0 no auto-receive, 1 Z-Modem auto-receive, -1 no change recho Set the remote echo flag on or off recho (int flg) flg: 0 means off, 1 means on save Set the save & display flag on or off save (int flg) flg: 0 means off, 1 means on send Send a text file over the serial output port send (char *name) result: error code. 0 if Ok. 2 if cancel. 3 abort (5 consecutive control-X characters received). All other values are Macintosh file system errors. name: File name setdtr Set DTR output line setdtr (int onoff) onoff: 0 to negate, 1 to assert setup Serial communications port setup setup (int baud, int data, int parity, int stop, char *port, int dtr, int hs) result: 0 if no error baud: 0=300, 1=600, 2=1200, 3=2400, 4=4800, 5=9600, 6=19200, 7=38400, 8=57600 baud (or -1 for no change) data: 0=7, 1=8 data bits (or -1 for no change) parity: 0=no, 1=even, 2=odd parity (or -1 for no change) stop: 0=1, 1=2 stop bit (or -1 for no change) port: port's name, e.g. "Modem Port" or "Printer Port" (or -1 for no change) dtr: 1=don't drop DTR when quitting (or -1 for no change) hs: Handshake 0=none, 1=XON/XOFF, 2=CTS, 3=DTR, 4=CTS/DTR stack Return free memory available for script heap and stack stack () result: Combined free heap and stack space (bytes) strcmp Compare two strings (not case sensitive) strcmp (char *str1, char *str2) result: 0 if strings are equal, positive if str1 > str2, negative if str1 < str2 str1: First string str2: Second string terminal Set terminal parameters terminal (int lecho, int recho, int autolf, int save) lecho: Local echo flag (or -1 if no modification) recho: Remote echo flag (or -1 if no modification) autolf: Auto line feed flag (or -1 if no modification) save: Save & capture flag (or -1 if no modification) text Set text file send parameters text (char *prompt, int lined, int chard) prompt: Prompt text lined: Ticks to wait after each line chard: Ticks to wait after each character time Return seconds from Macintosh clock time () result: Seconds type Send a string over the serial output port type (char *templ, ...) templ: Template string ...: Variable number of arguments (maximum 9) upload Upload (transmit) a binary file using X/Y/Z-Modem protocol upload (char *name, int bin, int zmodem) result: error code. 0 if Ok. 1 if timeout. 2 if cancel. 3 abort (5 consecutive control-X characters received). All other values are Macintosh file system errors. name: File name bin: 1 to recognize and use MacBinary format zmodem: 0 use X/Y-Modem, 1 use Z-Modem val Convert string to number val (char *str) result: Converted integer value str: Character string (0 terminated) xyparms Set binary file transfer options for X/Y-Modem xyparms (crc, k, batch, t) crc: 0 use checksum, 1 use CRC, -1 no change k: 0 use 128 Byte blocks, 1 use 1 KByte blocks "C", 2 use 1 KByte blocks "CK", -1 no change batch: 0 no batch (X-Modem), 1 batch official (Y-Modem), 2 batch RR (Y Modem), -1 no change t: timeout to use in ticks, -1 no change zparms Set binary file transfer options for Z-Modem zparms (ctl, t, retr, buf, pack, wind, crcq) ctl: 0 don't escape control characters, 1 escape control characters, -1 no change t: timeout to use in ticks, -1 no change retr: maximal retry count, -1 no change buf: receive buffer size in bytes, -1 no change pack: transmit sub-packet length in bytes, -1 no change wind: transmit window size in bytes, -1 no change crcq: transmit ZCRCQ spacing in bytes, -1 no change ___________________________________________________________________________ THE CONFIGURATION RESOURCE Some program parameters are kept in a configuration resource in the "Terminal" application. These parameters cannot be changed while the program is running, so there is no corresponding dialog in the "Options" menu. You must use "ResEdit" to change those parameters. "Terminal" includes the 'TMPL' (template resource) that "ResEdit" automatically will use to edit the configuration resource. All numbers are entered as decimal values. Buffer sizes are long integer values, i.e. maximum is 2147483647 bytes. The resource type is 'CNFG' and the id is 128. Label Default Description Reserved 0 Font size 9 Lines 24 Lines in terminal window Columns 81 Columns in terminal window Terminal buffer size 32768 Size of terminal buffer (bytes) Serial input buffer size 4096 Size of serial input buffer (bytes) Reserved 0 Script memory size 16384 Size of script memory (bytes) Font name Monaco Should be a monospaced font On a 9" screen Monaco 9 with 24 lines of 81 columns fills the entire screen. On a 13" screen Monaco 12 with 25 lines of 81 columns fills the entire screen. The terminal buffer can be greater than 32768 bytes, the only limitation is 32768 lines of text in the buffer, because of the way the vertical scroll bars is used in the terminal window. There is no practical limit for the other buffers, other than available memory. Note: if the buffer sizes are changed, the "SIZE" resource must be changed accordingly under MultiFinder, otherwise the program may not get enough memory. You can use the "About..." menu item to check for available memory while "Terminal" is running. There should be at least 32768 bytes free. With the original buffer sizes given "Terminal" runs fine in a 160K partition. ___________________________________________________________________________ HARDWARE Signal assignments for the mini 8-pin serial port connectors (from "Guide to Macintosh Family Hardware"): Pin Signal name Signal description 1 HSKo Handshake output. Driven inverted from SCC's /DTR. (That's what "Terminal" uses as DTR output) 2 HSKi Handshake input or external clock. Received uninverted at SCC's /CTS and /TRxC. (That's what "Terminal" uses as CTS input). 3 TxD- Transmit data (inverted). Driven inverted from SCC's TxD; tri-stated when SCC's /RTS is not asserted. 4 GND Signal ground. Connected to logic and chassis ground. 5 RxD- Receive data (inverted); received inverted at SCC's RxD. 6 TxD+ Transmit Data. Driven uninverted from SCC's TxD; tri-stated when SCC's /RTS is not asserted. 7 GPi General-purpose input (not connected on the Mac Plus). Received inverted at SCC's DCD. (That's what "Terminal" uses as DCD input). 8 RxD+ Receive data. Received uninverted at SCC's RxD. I have connected my modem (Abaton InterFax 24/96) with the following cable (this should be suitable for all high speed modems using hardware handshake): Mac mini 8-pin Modem 25-pin 1 (HSKo) --> 4 (RTS) and 20 (DTR) 2 (HSKi) <-- 5 (CTS) 3 (TXD-) --> 2 (TD) 4 (GND) 7 (Common) 5 (RxD-) <-- 3 (RD) 6 (TXD+) 7 (GPi) 8 (RxD+) 7 (Common) I have connected my Terminal Node Controller (Kantronics KAM) for packet radio with the following cable (hardware handshake in both directions): Mac mini 8-pin TNC 25-pin 1 (HSKo) --> 4 (RTS) 2 (HSKi) <-- 5 (CTS) 3 (TXD-) --> 2 (TD) 4 (GND) 7 (Common) 5 (RxD-) <-- 3 (RD) 6 (TXD+) 7 (GPi) 8 (RxD+) To interconnect 2 Macintoshes, or to connect the modem port to the printer port on the same Macintosh, I use an ImageWriter II cable. ___________________________________________________________________________ COMMENTS AND SUGGESTIONS Send any comments, bug reports and suggestions to my address: Erny Tontlinger 33, route d'Arlon L-8410 Steinfort Luxembourg or via electronic mail to my CompuServe account [73720,2200] (this can also be done via Internet using the address 73720.2200@compuserve.com). I'm a radio amateur, so you can reach me via the amateur packet radio network at LX1YZ @ LX0PAC or via TCP/IP as [44.161.1.1] lx1yz.ampr.org. This program is absolutely free, including the C sources. So do with it what you like, but please include the documentation if you give it away. If you use the program I would be happy to hear from you. ___________________________________________________________________________